eCryptfs

Q. What is novel about eCryptfs?

Well, nothing, to be honest. All of the techniques used in eCryptfs are directly based on cryptographic technology that was widely known and in practical use in the 1970's.

Security problems often arise when software tries to ``invent its own crypto'' by deviating from what has been in common practical use for a lengthy period of time. eCryptfs sticks to tried-and-true encryption technology.

In terms of per-file key management, eCryptfs simply uses the methods of PGP (created by Philip Zimmermann in 1991 and formally specified as a public standard in RFC2440 in 1998) and takes the obvious and conceptually trivial step of applying those methods within a filesystem service in the kernel. eCryptfs employs the well-weathered encryption techniques that have been in common use in the community for over two decades. Other cryptographic filesystems published and widely used in the 1990's use the same basic approach to encrypting files. eCryptfs just happens to be the first such filesystem to make it upstream in the Linux kernel.

Q. What versions of the kernel have eCryptfs support?

Linux kernel versions 2.6.19 and later have eCryptfs support. We provide experimental backports, but only the official mainline kernel is supported and is in active development.

Q. Will eCryptfs by itself protect all my data?

eCryptfs is just one component in a comprehensive set of mechanisms to protect the confidentiality of your data. Simply mounting eCryptfs over a directory in your home directory will probably not provide sufficient coverage for everything your applications will write to disk. For instance, applications that produce and store thumbnails of your images may write the thumbnails to an unprotected location.

Sensitive application data will typically wind up in the following locations, although some applications will write data to other locations not listed here:

• Anywhere in your home directory
• The /tmp directory
• The /var directory
• The swap device

The /tmp directory and the swap device can be easily protected with dm-crypt using a key randomly generated when the system is booted, since the information in those locations does not need to persist between reboots. eCryptfs must mount the /var directory prior to any daemons or other system applications reading from or writing to that location (including the syslog utility). eCryptfs must also mount over the user's home directory prior to the user logging into the system.

You will need to consider other applications that diverge from traditional paths for storing data on a case-by-case basis. Analyzing application behavior with the kernel auditing system is one way to profile the behavior of an application, and explicit SE Linux rules that only allow applications to write to encrypted mountpoints helps prevent inadvertent information leakage. We recommend always using eCryptfs together with appropriate Mandatory Access Control (MAC) mechanisms to ensure that your sensitive data is always encrypted.

Proper deployment of a comprehensive per-file encryption mechanism is a task best tackled by the entire Linux distribution. The eCryptfs team is working closely with various major Linux distributions to help ensure that eCryptfs is properly used as one component of a comprehensive data protection strategy.

Q. Can I access the lower files while eCryptfs is mounted?

Accessing the lower files during an active eCryptfs mount is somewhat like accessing a block device on which ext3 is mounted. The kernel allows it, and it may work (depending on what you do with the data), but it is not a good idea.

Q. What kernel options do I need to enable to build eCryptfs?

Code maturity level options --->
  [*] Prompt for development and/or incomplete code/drivers

Security options --->
  <M> Enable access key retention support

Cryptographic options --->
  <M> MD5 digest algorithm
  <M> AES cipher algorithms

File systems --->
  Miscellaneous filesystems --->
    <M> eCrypt filesystem layer support (EXPERIMENTAL)

Recommended .config options (some options not available in older kernels):
CONFIG_EXPERIMENTAL=y
CONFIG_KEYS=y
CONFIG_CRYPTO=y
CONFIG_CRYPTO_ALGAPI=y
CONFIG_CRYPTO_BLKCIPHER=y
CONFIG_CRYPTO_HASH=y
CONFIG_CRYPTO_MANAGER=y
CONFIG_CRYPTO_MD5=y
CONFIG_CRYPTO_ECB=y
CONFIG_CRYPTO_CBC=y
CONFIG_CRYPTO_AES=y
CONFIG_ECRYPT_FS=m

Newer versions of the Linux kernel now have a ``Layered filesystems'' submenu under the ``File systems'' menu, where eCryptfs and Unionfs reside.

Make certain that you have loaded all of the crypto modules that you need to run eCryptfs. This includes ecb, cbc, md5, and at least one popular symmetric cipher, like aes.

Q. On what filesystems can I expect eCryptfs to function?

Q. Why is the kernel stack such an issue with eCryptfs?

eCryptfs is a stacked filesystem. This implies that eCryptfs adds on top of whatever call stack exists with current filesystems. Each process in the Linux kernel has a fixed maximum stack size (4k+4k or 8k). Some filesystems (such as XFS) push the limit of the stack by themselves; adding eCryptfs on top may cause a stack overflow on these filesystems. If you wish to use eCryptfs on XFS, I recommend that you first perform stress tests to help determine whether your specific configuration will lead to a kernel process stack overflow.

Q. Can I mount eCryptfs with a public key?

You can mount eCryptfs with a public key if you have public key support (pubkey) in your kernel. You first need to generate a public/private keypair. Run ecryptfs-manager, follow the prompts to generate the keypair for the key module of your choosing, start the ecryptfsd daemon, and then specify the key module when mounting. For instance, for the OpenSSL key module, assuming you created your key in /usb-drive/mykey.pem and you want to do a layover mount on /secret, run:

# ecryptfsd
# mount -t ecryptfs -o key=openssl:keyfile=/usb-drive/mykey.pem /secret /secret

Q. Why would I want to use public key anyway?

Cryptographic keys derived from passphrases are generally worthless. Most passphrases that people can reasonably remember lack even the strength of a 64-bit symmetric key. The idea behind using a public key is to provide an opportunity for two-factor authentication; for instance, with OpenSSL RSA, the PEM file is ``something you have'' and the passphrase is ``something you know.'' This works best if you store your public key and your encrypted files on separate media.

The ``public key'' mode of operation in eCryptfs is actually more general than public key. It allows for arbitrary key modules to perform the File Encryption Key (FEK) encryption and decryption. The key module could do RSA. Or, it could retrieve an employee's key from a Domino server. Or, it could unseal the key protected by a Trusted Computing chip, which will only honor the unseal request if the machine is booted into a trusted state.

A key module now ships in ecryptfs-utils to interface with cryptographic tokens via PKCS#11. There is also a key module to interface with a TPM chip.

Q. What is ecryptfsd?

ecryptfsd is a daemon that runs as the user performing file operations under the eCryptfs mount point. It manages public key operations in userspace on file open events. ecryptfsd only needs to be run when a mount is done with a public key module.

Q. What is ecryptfs-manager?

ecryptfs-manager is an application that manages eCryptfs objects such as keys. You can use ecryptfs-manager to ask key modules to generate new keys for you, for instance.

Q. Do I have to be root to mount eCryptfs?

eCryptfs mounts can be set up to be done by non-root users. Generally, you want to perform the initial key generation and mount as the root user. Then, you can do a mount as a user by putting the appropriate options in /etc/fstab, adding the keys to the user session keyring (using ecryptfs-manager), and performing the mount in such a way that bypasses the mount helper. This is not very well automated in the current release, but it is possible right now with some manual steps. The instructions on using the PAM module are contained in the README and give the steps necessary to set that up; just follow all the directions except the last PAM step to see how it works:

Q. How do I store the metadata in the extended attribute region of the lower file?

If your kernel has support for it, mount with the -o xattr option. Be sure to preserve the extended attributes in the lower files, or you will lose your data. Bear in mind that many userspace utilities such as tar lack extended attribute support, and so you need to use utilities like star with the proper options instead.

Q. I am using the -o xattr option, but my backup tools do not preserve extended attributes. How can I back up the lower files?

Mount with the -o encrypted_view flag and read the files from under the eCryptfs mount point. The files read will be encrypted, and the cryptographic metadata will be in the headers of the encrypted files that are passed through, even if this metadata is actually stored in the extended attribute regions of the lower files.

Q. What about filename encryption?

The namespace problem arises when we consider the case where two files have the same unencrypted name. This can be a problem when the user does not have the key for every file in any given directory. Imagine, for instance, that Alice creates a file named ``meeting_notes.txt'' in a shared directory on an NFS server. The filename is encrypted with a key known only to Alice and Carol. Bob then creates a file in the same shared NFS directory and also names it ``meeting_notes.txt'', encrypting the filename with another key only known to Bob and Carol. Bob's eCryptfs client cannot detect the unencrypted filename conflict in the namespace because Bob does not have Alice's key.

So two different files that have the same unencrypted name and different encrypted names appear in the same directory. When Carol, who has both Alice's key and Bob's key, lists the contents of the directory, he winds up seeing two different files with the same filename in the same directory, which is a POSIX violation.

The solution we may implement is to use a separate key just for filename encryption, requiring all filenames encrypted under any given directory to be encrypted with that key. Filename encryption is a planned feature, but there is currently no set date for when it will be completed.

Q. What about sparse files?

eCryptfs does not currently support sparse files. Sequences of encrypted extents with all 0's could be interpreted as sparse regions in eCryptfs without too much implementation complexity. However, this would open up a possible attack vector, since the fact that certain segments of data are all 0's could betray strategic information that the user does not necessarily want to reveal to an attacker. For instance, if the attacker knows that a certain database file with patient medical data keeps information about viral infections in one region of the file and information about diabetes in another section of the file, then the very fact that the segment for viral infection data is populated with data at all would reveal that the patient has a viral infection.

Q. How should I select my passphrase?

Q. How can I protect my key?

Make a copy and store it in a physically secure location. For instance, copy your public/private keypair to a USB flash drive or write your passphrase onto a sheet of paper. Then, lock the drive and paper in your desk drawer or put them in a safe deposit box (depending on the sensitivity of the data that the keys protect). Future versions of eCryptfs userspace utilities may implement key splitting functions to provide even more paranoid levels of key protection.

Do not store your keys under the same physical security context in which you are storing your media. It should be much harder for an attacker to get to your keys than it is for him to get to your media.

When you use public key mode and generate a new key using ecryptfs-manager, the generated key file is the one that you must back up in order to access your files.

When mounting with a new key, I recommend performing a full mount, creating a new file, unmounting, clearing the user session keyring (keyctl clear @u), mounting again, and then trying to access the newly created file. This minimizes the likelihood that you will mistype a passphrase and create files that you will not be able to later recover. When mounting in passphrase mode, make sure that the ecryptfs_sig value matches between mounts. To help avoid the pitfall of mistyping a passphrase on mount, eCryptfs stores a cache of previous ecryptfs_sig values and warns the user if a mount passphrase does not match any passphrases used for previous mounts.

Q. I forgot my password/lost my key! What can I do to recover my data?

Q. How does eCryptfs compare with other Linux disk encryption solutions?

eCryptfs is an actual filesystem. Some other popular disk encryption technologies are not filesystems; they are block device encryption layers (they provide what appears to be a physical block device to some actual filesystem). There is no filesystem logic in these layers. A few of the more well-known block device encryption layers include dm-crypt, Truecrypt, and Loop-AES. Perhaps the best thing about block device-layer encryption is that it is an order of magnitude simpler to implement than filesystem-layer encryption. Another advantage of block device-layer encryption is that it will encrypt the entire filesystem, including all of the filesystem metadata. However, for many use cases, this can turn out to be more of a disadvantage than an advantage.

While eCryptfs uses a powerful and flexible approach to protecting filesystem content, block device-layer encryption technology is still required to protect swap space and certain databases that use their own block device partition. The table below provides a compare-and-constrast of the two technologies. I anticipate that block device encryption will be the best solution for some people, while stacked filesystem encryption will be the best solution for others. Sometimes it even makes sense to use them both together, to combine the comprehensive full-disk encryption of a block device layer encryption technology with the transparent per-file encryption provided by eCryptfs (this will result in double-encryption of the file contents).

EncFS is another popular cryptographic filesystem that behaves much like a stacked filesystem. EncFS is a userspace filesystem, and so individual page reads and writes require additional context switches between kernel and userspace. One advantage a userspace cryptographic filesystem is that it is possible to use symmetric ciphers implemented in userspace libraries, but the frequent context switching impacts performance.

Why does the eCryptfs daemon crash my kernel?

You are probably using a kernel with the netlink interface to the userspace daemon. The netlink interface with the userspace daemon is buggy and obsolete.

Once one user can access an eCryptfs file, any users with permission can also access the file. Should not eCryptfs require all users to have the key in order to access the files?

eCryptfs deliberately makes no attempt to re-implement the discretionary and mandatory access control mechanisms already present in the Linux kernel. eCryptfs will simply require that a File Encryption Key (FEK) be associated with any given inode in order to decrypt the contents of the file on disk. This prevents an attacker from accessing the file contents outside the context of the trusted host environment; for instance, by removing the storage device or by booting a live CD. This is the only type of unauthorized access that eCryptfs is intended to prevent.

Once eCryptfs has associated that FEK with the inode, it does not impose any additional restrictions on who or what can access the files, deferring to the standard user/group/other permissions, capabilities, SE Linux type enforcement, and so forth to regulate access to the files. eCryptfs maintains no pedigree regarding how the FEK found its way to the inode, so it has no way of knowing that any particular UID should or should not be able to open the file, nor should eCryptfs do such a thing.

Having eCryptfs impose additional access control onto the decrypted file contents in a trusted host environment would provide no additional security while introducing unintended usability issues. For instance, a user may wish to share his decrypted files with certain other users on the system without having to share his key with them or add their keys to a set of keys wrapping the inode's FEK. Users expect to be able to accomplish such a task via users, groups, capabilities, and types, and eCryptfs defers access control decisions on trusted host environments to these existing access control mechanisms.

Q. "Unable to allocate crypto cipher with name [---]; rc = [-2]"

Make sure that you have enabled the kernel crypto API and that you have built the ciphers, hashes, and chaining modes that you wish to use. This will usually be md5, aes, cbc, and ecb. Also, make sure that the requested key size is valid for your cipher.

Q. "Error mounting eCryptfs; rc = [-2]; strerr = [No such file or directory]"

Make sure that both the source and destination directories that you provide to the mount command exist.

Q. "ecryptfs_parse_options: Could not find key with description: [deadbeaf...]"

If the mount fails and the message "ecryptfs_parse_options: Could not find key with description: [deadbeaf...]" is in your system logs, then there was a problem inserting your mount key into your kernel user session keyring.

After a mount attempt, run keyctl_show. You should see something like this:

# keyctl show
Session Keyring
       -3 lswrv----------     0     0  keyring: _uid_ses.0
        2 lswrv----------     0     0   \_ keyring: _uid.0
892244932 lswrv----------     0     0       \_ user: deadbeef...

Where deadbeef is the signature that corresponds with your key. If you don't see this, then there is a problem with your keyring setup.

If you su to root, be sure to initiate the session by using the - flag.

Finally, try linking your user keyring into your active session keyring:

# keyctl link @u @s

Q. "ecryptfs_parse_packet_set: Expected signature of size [8]; read size [7]"

Older versions of eCryptfs shipping in older kernels had a minor bug where eCryptfs would only write out and read in 7 of the 8 key signature characters to the metadata of the lower file. This violates the eCryptfs spec, so newer versions of eCryptfs correct this bug and refuse to read files that do not conform to the spec.

The current correctly implemented version of eCryptfs cannot read files created with the early nonconformant and buggy release. If you have any files created with the earlier version, you will need to boot with the earlier version of eCryptfs and copy the decrypted files to secure location (e.g., a loopback mount image protected with dm-crypt). You will then need to copy the data from the secure location into an eCryptfs mount using the most recent kernel release.

Note that the Versions of eCryptfs from 2.6.24 and on will be able to read files created by earlier versions, back through to 2.6.24, as indicated in the ecryptfs-utils package README file:

eCryptfs is still in a developmental stage. When you upgrade the eCryptfs kernel module, it is possible that the eCryptfs file format has been updated. For this reason you should copy your files to an unencrypted location and then copy the files back into the new eCryptfs mount point to migrate the files. File format version 3 and beyond (in kernel version 2.6.24) is expected to remain readable, however.

Q. My question isn't answered here.